"""
mc.future模块的类型stub

提供future/promise相关的类型定义，用于类型检查和IDE提示。
"""

# @mcpy_headers: <mcpy/builtins/async.h>
# @mcpy_namespace: mcpy

from typing import (
    TypeVar,
    Generic,
    Callable,
    Generator,
    Any,
    Coroutine,
)

T = TypeVar("T")
R = TypeVar("R")


# @mcpy_type_alias: cpp_type=mcpy::future<{T}>, default_type=mcpy::future<void>
class future(Generic[T]):
    """表示一个异步操作的future"""

    def get(self) -> T:
        """同步等待并获取结果"""
        ...

    def then(self, callback: Callable[[T], R]) -> "future[R]":
        """添加完成后的回调"""
        ...

    def catch_error(self, callback: Callable[[Exception], T]) -> "future[T]":
        """捕获异常"""
        ...

    # @mcpy_method_template: finally_(callback) -> future[T] = {self}.finally({callback})
    def finally_(self, callback: Callable[[], None]) -> "future[T]":
        """无论成功失败都执行的回调（Python名称与C++不同）"""
        ...

    def tap(self, callback: Callable[[T], None]) -> "future[T]":
        """观察值但不改变future"""
        ...

    def cancel(self) -> None:
        """取消操作"""
        ...

    def is_ready(self) -> bool:
        """检查是否已完成"""
        ...

    def is_cancelled(self) -> bool:
        """检查是否已取消"""
        ...

    def is_rejected(self) -> bool:
        """检查是否已异常"""
        ...

    def __await__(self) -> Generator[Any, None, T]:
        """支持在 async 语法中对 future 使用 `await`

        类型层面提供 `__await__` 以使静态类型检查器认定其为 Awaitable[T]。
        具体行为由运行时或代码生成端实现。
        """
        ...


# @mcpy_type_alias: cpp_type=mcpy::promise<{T}>, default_type=mcpy::promise<void>
class promise(Generic[T]):
    """表示一个promise，用于设置future的值

    对应C++的mc::promise<T>类型。
    """

    def get_future(self) -> future[T]:
        """获取关联的future"""
        ...

    def set_value(self, value: T) -> None:
        """设置值"""
        ...

    def set_exception(self, ex: Exception) -> None:
        """设置异常"""
        ...

    def cancel(self) -> None:
        """取消promise"""
        ...


def make_promise() -> promise[T]:
    """创建一个promise"""
    ...


def resolve(value: T) -> future[T]:
    """创建一个已完成的future"""
    ...


def reject(ex: Exception) -> future[T]:
    """创建一个已异常的future"""
    ...


def all(*futures) -> future:
    """等待所有future完成"""
    ...


def any(*futures) -> future:
    """等待任意一个future完成"""
    ...


def gather(*futures) -> future:
    """等待所有 future 完成（asyncio.gather 的别名）"""
    ...


# @mcpy_emit_template: mcpy::sleep({duration_ms})
# @mcpy_headers: <mcpy/builtins/async.h>
def sleep(duration_ms: int) -> Coroutine[Any, Any, None]:
    """延迟执行"""
    ...


def timeout(f: future[T], duration_ms: int) -> future[T]:
    """为future添加超时"""
    ...


# @mcpy_type_alias: cpp_type=mc::result<{T}>, default_type=mc::result<void>, satisfies_protocols=Coroutine
class result(Generic[T]):
    """表示一个result（可能是值或错误）

    result[T]满足Coroutine协议，因此：
    1. async函数返回result[T]可以被识别为Coroutine类型
    2. 可以传递给期望Coroutine[Any, Any, T]的函数（如ensure_future）
    3. 支持await语法
    """

    def get(self) -> T:
        """获取结果值（如果有错误会抛出异常）"""
        ...

    def has_error(self) -> bool:
        """检查是否有错误"""
        ...

    def as_future(self) -> future[T]:
        """转换为future"""
        ...

    def __await__(self) -> Generator[Any, None, T]:
        """支持await语法（Coroutine协议要求）"""
        ...


# @mcpy_emit_template: mcpy::ensure_future({obj})
# @mcpy_headers: <mcpy/builtins/async.h>
def ensure_future(obj: Coroutine[Any, Any, T]) -> future[T]:
    """将 Coroutine 转换为 future

    Python类型转换：
        Coroutine[Any, Any, T] -> future[T]

    使用示例：
        async def get_value() -> int:  # 返回result[int]，满足Coroutine协议
            return 42

        res = get_value()  # 类型：result[int] (满足Coroutine[Any, Any, int])
        fut = ensure_future(res)  # 类型：future[int]
        value = fut.get()  # 可以调用future的方法

    C++实现：
        使用mcpy::ensure_future智能适配器，支持：
        - mc::future<T> -> 直接返回
        - mc::result<T> -> 调用as_future()转换
        - 其他类型 -> 通过mc::resolve包装
    """
    ...
